Complications on the watch, and a Wear artifact beside the phone APK - #5583

Three preliminaries for generating watch complications, each of which stands on
its own.

A result entry's role suffix now survives into the copied artifact name. Every
entry used to land on target/<finalName><extension>, keyed on the extension
alone, so a build returning two artifacts of the same kind -- a phone APK and a
companion Wear APK beside it -- collapsed both onto one path and the last one
written won. That corrupts the primary artifact, not merely the secondary one,
and it does it silently.

The family classification moves into SurfaceKindFamilies, which also reads the
portable "families" key with "iosFamilies" as its legacy spelling. The Android
builder has to tell a home-screen kind from a complication kind and is not going
to parse a key with "ios" in its name. Delegation rather than a second copy,
because the rule is subtle enough that three call sites once implemented it as
startsWith("watch") and all three got accessoryCircular wrong.

The shared surfaces Swift now compiles for watchOS. Four WidgetKit system
families are @available(watchOS, unavailable) -- unnameable, not merely absent --
and UIColor.systemBackground, UIColor(dynamicProvider:) and
UIGraphicsImageRenderer are all API_UNAVAILABLE(watchos); the file named all of
them unconditionally. The substitutes are the right answers rather than
degradations: a watch face composites over black and has no light appearance, so
the background role is black and a light/dark pair resolves to its dark half.
Images downsample through ImageIO, which decodes at the target size so the
full-size bitmap is never resident, at a quarter of the phone's ceiling.

Verified by typechecking the sources against both the watchOS and iOS SDKs.
SurfacesSwiftWatchPortabilityTest is the half that also runs on a CI leg with no
Xcode; it was confirmed to fail when the systemBackground guard is removed.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Five review findings, four of which were the same shape: code that compiles,
never throws, and renders nothing.

**Containers were read under the wrong key.** `SurfaceContainer` serializes its
children as `ch`; both the complication reader and the Tile renderer looked for
`c`. Every row, column and box therefore looked empty, so a complication mined a
layout with no text, no progress and no imagery in it and a Tile rendered
nothing. That is indistinguishable from an app that published nothing, which is
why it survived a green build.

**Dynamic nodes carry no text to interpolate.** A `dyn` node serializes a style
plus a date or a dateKey, so asking it for `text` resolved to an empty string and
every countdown, clock and relative date vanished. They now go through the core's
own formatter -- made public rather than copied -- so a countdown reads the same
on a watch face as in the simulator preview and on a home screen.

Both are now pinned by SurfaceWatchWireFormatTest, which asserts the field names
against the serializer itself. The readers live in the Android port and cannot be
unit tested from there, but the wire format can be, and that is what makes this
kind of drift visible instead of silent.

**A Tile tap dropped its action.** A Clickable's id is ProtoLayout interaction
metadata and never reaches the started activity, so the trampoline -- which
dispatches only when EXTRA_ACTION_ID is present -- opened the app and discarded
the action id, source and parameters. The extras are attached explicitly now, the
same three a widget tap sends.

**A companion build raised the phone's minSdk.** Declaring a watch family pushed
the shared floor to 26 before the phone module's Gradle file was written, so a
phone APK that had supported API 21-25 became uninstallable on the devices it
already served. The floor now rises only for a standalone build, where the app
module IS the watch product; the wear module sets its own.

**Mirrored artwork never triggered a redraw.** A file transfer is asynchronous
and unordered against the descriptor, so art routinely lands after the timeline
that references it -- and only the descriptor asked for a refresh. The first
render showed a gap and nothing asked again until the next publish.

Also fixes the two SpotBugs findings that failed CI: mkdirs() return values were
ignored. The naive check is wrong here, since mkdirs() answers false both when
the directory could not be created and when it already exists -- which is the
common case -- so existence afterwards is what the callers test.

SpotBugs is now zero across android, ios, codenameone-maven-plugin and
core-unittests; 917 plugin and 5202 core tests pass.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Four more findings from the second review round, three of which meant a
generated artifact could not work at all.

**The watch slice lost the surfaces define.** CN1_USE_WIDGETS was still flipped
only for surfacesExtensionEnabled, so a manifest declaring nothing but
complications compiled the watch slice without it -- and since the
WatchConnectivity delegate calls cn1_watch_apply_mirrored_surface, which that
define guards, the watch slice failed to LINK rather than merely doing nothing.

That edit was written once before and lost: a patch script asserted on a later
anchor and never wrote the file. The same failure ate the daemon's
appendWidgetExtension call site. Both are now verified present rather than
assumed.

**The Wear module declared no Data Layer listener.** Its manifest is selected
outright by the module's sourceSets rather than merged with the phone's, so
nothing the phone declares reaches it -- and the watch needs this one more than
the phone does, being the half that RECEIVES a mirrored complication. Play
services had nothing to bind in the watch APK, so every mirrored descriptor was
dropped and complications stayed at whatever the watch had published for itself.

**Tile padding was read as an object.** SurfaceNode serializes it as the array
[top, right, bottom, left], which is what the RemoteViews renderer reads, so
asking for an object returned null for every valid descriptor and all declared
padding was silently discarded.

**A Tile's vector resources were keyed by object identity.** The layout request
and the resources request are separate calls that each re-read and re-parse the
timeline, so the two ids never matched: the layout referenced a resource the
returned map did not contain and every vector rendered as a missing image. The
id now comes from the node's serialized content, which is equal across parses --
and two identical vectors sharing one resource is correct, since they draw the
same thing.

SurfaceWatchWireFormatTest grows the padding and vector cases, so the class of
bug that produced three of these four -- reading a field the serializer does not
write -- is pinned against the serializer rather than found by review.

SpotBugs zero across android, ios, codenameone-maven-plugin and core-unittests;
917 plugin and 5204 core tests pass.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

The Android CI failure and four more review findings, all of them the same
mistake in different places: the phone and the watch are separate products in a
companion build, and things scoped to one kept reaching the other.

**The androidx.wear libraries reached the phone module.** They went into the
shared gradleDependencies hint, which in a companion build feeds both modules --
and they declare minSdk 26 while the phone keeps its own floor. A phone app on
API 24 therefore stopped building the moment a watch family was declared, failing
its manifest merge against libraries it never uses. They now go into the wear
module's own dependency block, and only a standalone build -- where that single
module IS the watch -- puts them in the shared one.

**The Data Layer glue was decided before the kinds were parsed**, so
watchSurfaceKinds was always empty at that point. An app that publishes
complications and never writes a line of com.codename1.wearable got no glue, no
dependency and an empty listener declaration -- the mirror had no transport at
either end. The block moves after the surfaces parse.

**A watch-only manifest could not mirror at all.** The phone was deliberately
left without the App Group entitlement, so its container did not resolve,
areWidgetsSupported() answered false, and Surfaces.publish() returned before the
bridge -- taking the mirror with it. The one manifest this feature exists for was
the one that could not update its own complications. The group is genuinely part
of the plumbing on both bundles and is now entitled on both.

**The Wear manifest declared no INTERNET permission.** It receives only the
scanned permissions, not the base ones, and is selected outright rather than
merged -- so a watchMain making an ordinary Codename One network request failed
while the same code worked on the phone.

**The watch bundle declared no cn1surface URL scheme.** A complication supplies a
cn1surface:// widgetURL and the generated scene waits for it in onOpenURL, but
the watch is a separate bundle inheriting none of the phone's URL types. watchOS
had nothing to route the tap to, so the whole tap-dispatch path was inert.

Two new tests pin the module boundary: that a companion phone module carries no
androidx.wear dependency, and that the watch bundle declares the scheme when it
hosts a complication and does not otherwise.

SpotBugs zero across android, ios and codenameone-maven-plugin; 920 plugin tests
pass.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

The CI failure and two more review findings, all from the same root: the Wear
module's build.gradle is derived from the phone's by textual substitution, and a
generated Gradle file only fails when Gradle evaluates it -- twenty minutes after
the mistake, in a job that names none of it.

**The androidx.wear dependency landed in the buildscript block.** The anchor was
"dependencies {", which matches the indented buildscript block FIRST -- and
String.replace hits every occurrence -- so an implementation() call went into
buildscript's dependency handler, where the method does not exist. The whole
:wear project failed to evaluate. Anchored on "\ndependencies {" now, which only
the project block matches.

**The Wear module looked for a keystore beside itself.** Gradle resolves
file("keyStore") relative to the project it appears in, and the certificate is
written only to the app module -- so a companion release build failed to
CONFIGURE, taking the phone artifact with it. Not the watch half degrading: the
whole build not starting.

**The generated services were written into the phone's source root.** The wear
module shares that directory, so the phone compiled androidx.wear imports it has
no libraries for -- the exact mirror of the dependency-scoping fix that preceded
it. They now go to the wear module's own root. The kind-list resource stays on
the phone deliberately, because the mirror reads it THERE to decide what to send.

**The Tile service was copied whether or not a Tile was declared**, while its
dependencies were added only for a rectangular family. Gradle compiles every
source in the tree, so a complication-only build failed on unresolved imports.

The derivation is now a static function, and WearModuleGradleTest pins each
substitution against a build.gradle shaped like the real one -- the dependency
landing in the project block and not buildscript's, the keystore reachable, the
libraries shared, the phone's floor untouched. It calls the real builder rather
than reproducing it, and was confirmed to fail on the exact anchor bug that broke
CI. Two more tests cover where the services are generated and which are copied.

SpotBugs zero across android, ios and codenameone-maven-plugin; 928 plugin tests
pass.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Two breaks in last round's push retargeting, both of which would have
failed the wear build outright.

The exclusion removed BOTH copies. A Gradle exclude applies to the whole
source set, and the phone root and the module's own root hold the same
relative path -- so '**/StubUtil.java' took out the watch-specific
replacement along with the phone's, leaving the shared messaging service
referencing a class that was no longer compiled at all. It is scoped by
absolute path now, so only the file under app/src/main/java is dropped.

And the replacement was missing getMain(). Every bundled
CN1FirebaseMessagingService template calls it, so a companion build with
FCM failed on a class the developer never wrote. All three of the phone
copy's methods are mirrored now, with the same visibility and return types
-- getMain package-private and returning Object, as it is there.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

…tands still

An image name is a CLAIM about the bytes beside it, and a descriptor from a
server or the watch mirror came from outside this process. iOS skips
writing a blob whose file already exists, on the strength of that claim --
so corrupted bytes landing first cannot be repaired by any later legitimate
publish, and the surface shows wrong artwork for good. Hash-shaped names
are now checked against their content, reusing the serializer's own fnv1a
rather than a second copy. A name that was never a hash is passed through
rather than refused for failing a test that does not apply to it.

Tile freshness claimed movement from things that had stopped moving. A
finished interval is clamped at its completed value, a time or date style
formats the node's own fixed timestamp, and an expired countdown sits at
zero -- yet each of them asked for a rebuild every minute, for ever,
redrawing an identical Tile at the cost of the refresh budget and the
battery. The question is now whether the content is still moving, not
whether it is the kind of content that can.

And an interval sample whose entry cannot render the requested type left
its stretch uncovered: the base entry had already been ended at the first
sample, so the timeline fell back to its default -- the older reading,
resurfacing after it stopped being current. It substitutes no-data, exactly
as the main loop does.

hasDynamicText went with the freshness change; nothing called it any more.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Four refinements, all of the same shape: a value the face could advance was
being handed over frozen, or not handed over at all.

The interval sampler stopped short of the interval's own end, so a
twelve-step gauge climbed to about eleven twelfths and stayed there -- the
last entry ran on indefinitely holding a partial value and the one moment
the bar is actually full was never shown. The endpoint is emitted when the
interval finishes inside the reading; when a flip covers it instead,
nothing is added, because the flip already ends that entry. Checked against
a whole interval, one clipped by a flip, and one already over.

A SHORT_TEXT title is displayed and could tick, and did not: a countdown
put in the second node froze exactly as the primary one used to.

A RANGED_VALUE description and a LONG_TEXT description whose title is the
only moving part were both still request-time strings, so a screen reader
announced a time long after the face had moved on. Whichever part actually
moves now describes the whole -- the body when both move, being the value
rather than the label.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

The active reading's own start is in the past, so sampling from there
emitted timeline entries whose intervals already cover the present -- and
one of them then overrides the default, which is the only value built for
the current moment. A week-long interval sampled twelve times showed a
gauge fourteen hours stale the instant it appeared. Sampling starts no
earlier than now; a future reading is unaffected, because now is before its
start and the clamp does nothing there. Checked against both.

And a Tile treated an interval that had not BEGUN as moving, because the
check asked only whether it had ended. A reading published hours ahead
therefore asked for a rebuild every minute throughout, redrawing a bar
clamped at zero. Running now means started as well as unfinished.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Refusing periodic refresh before an interval begins was right -- the bar is
clamped at zero until then, and asking every minute redrew an identical
Tile for hours. On its own, though, it left nothing to wake the Tile AT the
start, so a reading with no flip date would have sat at zero indefinitely:
the fix for the waste created a freeze.

The freshness is now the earlier of the flip date and the moment something
starts moving. One refresh at that moment is enough -- the rebuild then
sees the interval running and asks for the periodic rate itself.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

A static value beside a ticking title left the description a snapshot: the
visible title advanced while a screen reader went on announcing its
request-time value, and with no update period nothing corrected it. The
rule the long-text branch already follows now holds here as well --
whichever part moves describes the whole, the value first and then the
title.

The comment block had accumulated three overlapping paragraphs as this
branch was corrected round by round; it says the whole rule once now.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

reload-at-end did nothing on a companion watch. The refresh request looks
up a background-fetch listener recorded by publishWidgetTimeline -- and a
watch never runs that method: its descriptors arrive through
CN1SurfaceMirror.receive instead. So the preference was unset, the request
returned immediately, and a mirrored complication sat on its final entry
until the phone happened to publish.

Asking the watch was the wrong device anyway. The content is produced on
the phone, so the request now goes back up the link the descriptor came
down: a reserved /cn1surfacereload path, routed like the descriptors
themselves before anything app-visible, answered on the phone by the same
throttled request a widget makes. Absent everywhere it does not apply -- a
build with no wearable link has no bridge to call, and an older injected
bridge has no such method, both of which leave the previous behaviour.

The scheduled form asks immediately rather than at the timeline's end,
because the alarm needs a local component to deliver to and a mirrored
watch has none. That is stated where it is done rather than left to look
like an oversight.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

The peer fallback I added last round loops. A watch with no listener asks
the phone; the phone answers by calling the same method, finds no listener
either, and asks the watch back -- neither ever acquires one, so the two
wake each other until they disconnect. An answer to a peer's request is now
forbidden to ask a peer: it asked because it has nothing, and this device
having nothing either is the end of it, not the start of a round trip.

And the integrity check never ran. Serializer names are "img" plus sixteen
hex digits, while the predicate demanded exactly sixteen characters -- so
it matched nothing the framework produces, and had it matched it would have
compared a prefixed name against an unprefixed hash and rejected every
legitimate blob. Both halves now use the prefix, and a name that was never
a hash is still passed through rather than failing a test that does not
apply to it. Checked on a real generated name: recognised, matching bytes
accepted, corrupted bytes rejected, an app-registered name left alone.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Only the head of the complication queue is ever handed to WCSession -- that
is what keeps a prioritised transfer from displacing the one before it --
so everything behind it lived in memory alone. A suspension or termination
during a background transfer took those kinds with it, and no system-owned
transfer existed for them either, so their complications stayed stale until
something else published. The queue is parked on disk now and read back on
activation, which is the one thing that always happens whatever brought the
process up. A kind published since the restore is newer than what was
parked, so the parked copy is dropped rather than overwriting it.

The same idiom the received-transfer inbox already uses, and for the same
stated reason: the process does not own its own lifetime.

And a count-up toward a future target reads 0:00 until it arrives, so a
Tile carrying one asked for an identical rebuild every minute through the
whole wait. It is dormant now and wakes at its target, exactly as a
not-yet-started interval does -- the two cases are the same shape, so they
share the one method that decides when to come back.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

shared activates WCSession asynchronously, so the first publish in a fresh
process reaches the mirror before activation completes -- and until it
does, isPaired and isWatchAppInstalled are not reliable and a transfer may
be refused outright. Deciding there discarded the only copy of that payload
on the strength of an answer the session was not ready to give, and nothing
would have sent it again.

An unactivated session now queues instead, which also parks the payload on
disk, and activationDidCompleteWithState sends it once the session can
actually be asked. The queue drain refuses to run before activation for the
same reason: spending payloads on transfers that may be refused is the
discard this queue exists to prevent.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

A publish is a write followed by a hand-off: the platform replaces the
timeline in its container and then gives the same descriptor to the watch,
and the two are only meaningful as a pair. Let two publishes of one kind
interleave and the later write pairs with the earlier hand-off, so the watch
is left holding a descriptor the phone has already replaced -- and left
holding it for good, because nothing publishes again to correct it. The
imagery is worse than stale: both platforms read the blobs back off disk at
hand-off time, so one publish's descriptor could be sent with another's
artwork, a pairing neither publish ever produced.

publish() documents itself as callable from any thread, so two threads
publishing one kind is a supported way to call it. The monitor is per kind
rather than global, since a publish is file I/O plus a synchronous native
call and two kinds have nothing to say to each other. publishRemote takes
the same one: a push landing while the app publishes races identically.

Also returns the Wear module's R8 map with the build. It could not ride the
source export -- that zip excludes every directory named "build", which is
where R8 writes -- so a companion build's watch frames had no map at all.
The new test pins the naming the extractor pairs it by.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

The delivery ladder ran at the publish: pairing and installed-app first, then
the budgeted complication wake, falling back to a plain queued transfer when
no complication is placed or the daily budget is spent. Only payloads that
wanted the wake were queued, so the queue could send them blind.

Two paths now reach that queue without having been judged. A publish that
arrives before the session activates is queued precisely because the session
cannot be asked yet, and a queue restored from disk was judged in a previous
run of the app, if at all. Both were then sent down the budgeted path
regardless -- spending a transfer on a watch with no complication placed, or
on a budget already exhausted, where the resulting exception retires the
payload. That is the discard the queue exists to prevent.

The ladder moves to the send, which is the only point where every payload
passes through it and where the session's answers are current. The publish
keeps one cheap test, for a phone with no watch at all, so the common install
does not write a queue file and delete it again -- labelled as the fast path
it is, with the authoritative copy naming it.

Also carries android.xmanifest's uses-sdk attributes into the Wear manifest.
A tools:overrideLibrary is how a project accepts a dependency whose manifest
demands a higher minSdk than the app declares, and since the wear module
keeps the phone's dependency graph it merges that same library manifest --
so a project that builds today failed in the wear merge instead.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>